Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

NS_DEV_DOCFOR:objc_protocol:NXReadOnlyTextStream;,NXReadOnlyTextStream

Adopted By:	Text

Declared In:	appkit/readOnlyTextStream.h

Protocol Description

This is the protocol that a delegate of NXSpellServer uses to provide the text to be spell-checked.  An object that implements this protocol is one of the arguments to the NXSpellChecker method that initiates a spell-checking session. 

The data provided by NXReadOnlyTextStream must contain purely NEXTSTEP-encoding charactersÐthe spell checker doesn't support multiple byte characters.  Since one byte in the stream must equal one character, 16-bit entities (such as those in the KANJI system) must be converted to obvious break characters (such as space) before being handed out by this protocol.  All formatting characters and other nontext characters should be completely stripped out.  Only the actual one-byte NEXTSTEP-encoded characters should come through this protocol.

Note that an object that wants to use spell-checking may choose to break data up into lots of little NXReadOnlyTextStreams.  One example of this is when you have multiple languages within a document in your application. You can return YES in the method isAtEOTS (and stop returning characters via readCharacters:count:) whenever you reach the end of one language and the beginning of another.  You can then tell the NXSpellChecker object to switch languages and start another spell checking session on subsequent text.

Note that the currentCharacterOffset method should always return a value reflecting either the position of the insertion point of the text, or the start of the selection in the text, or, if neither of those exists, the start of the text.  This means that the NXReadOnlyTextStream is expected to be valid only for the duration of a single invocation of checkSpelling:of:.

Method Types

Opening and closing the stream	- openTextStream
- closeTextStream

Reading from the stream	- readCharacters:count:

Positiioning within stream	- seekToCharacterAt:relativeTo:
- currentCharacterOffset
- isAtEOTS

Instance Methods

NS_DEV_DOCFOR:objc_method:[NXReadOnlyTextStream-closeTextStream];,closeTextStream

- closeTextStream

Closes the text stream, returns self.  This method is invoked at the end of a spell-checking session. 

NS_DEV_DOCFOR:objc_method:[NXReadOnlyTextStream-currentCharacterOffset];,currentCharacterOffset

- (int)currentCharacterOffset

Returns, at the beginning of the spell-checking session, either the insertion point of the text, or the start of the selection in the text, or, if neither of those exists, the start of the text on the stream.  The value returned by this method should be updated to reflect the new position each time readCharacters:count: is invoked. 

NS_DEV_DOCFOR:objc_method:[NXReadOnlyTextStream-isAtEOTS];,isAtEOTS

- (BOOL)isAtEOTS

Tests whether the receiver has reached the end of the text stream.  Returns YES if it has, NO if not. 

NS_DEV_DOCFOR:objc_method:[NXReadOnlyTextStream-openTextStream];,openTextStream

- openTextStream

Opens the text stream, returns self.  This method is invoked at the beginning of a spell-checking session. 

NS_DEV_DOCFOR:objc_method:[NXReadOnlyTextStream-readCharacters:count:];,readCharacters:count:

- (int)readCharacters:(char *)buffer count:(int)count

Requests character data from the NXReadOnlyTextStream, beginning at the current position. count is the number of characters requested.  buffer represents the storage into which those characters should be copied.  This method returns the number of characters actually placed on the stream, which may be less than count if the number of characters remaining in the text is less than count. 

NS_DEV_DOCFOR:objc_method:[NXReadOnlyTextStream-seekToCharacterAt:relativeTo:];,seekToCharacterAt:relativeTo:

- (BOOL)seekToCharacterAt:(int)offset relativeTo:(int)seekMode

Sets the current position for reading characters from the NXReadOnlyTextStream. offset represents the number of characters to move, and may be negative if, for example, the seek is from the end of a stream.  seekMode represents the position from which to begin the seek; it should be one of the constants NX_StreamStart, NX_StreamCurrent, and NX_StreamEnd.  Returns YES if the current position was set successfully as specified.